Documentation Suite v24.4

Submit Search

Certificate Search Page

The search function allows you to query the database for information. The same query structure is used in multiple locations within the Keyfactor Command Management Portal.

When you first open the page, you will see the simple search option. To execute a search, select the field and comparison operators in the dropdowns and type something on which to search in the value field (if applicable). If you select an is null or is not null comparison operator, the value field will be grayed out. Click the Search button to execute the query.

Each query consists of three parts:

Comparison Operator

The query comparison operators vary depending on the type of field selected and the specific properties of the field. The list below shows the dropdown list comparison operators, as well as the equivalent query language syntax (in parentheses).

Most string fields (the vast majority of the built-in fields) support:

Is equal to (-eq)
Is not equal to (-ne)
Contains (-contains)
Does not contain (-notcontains)

Starts with (-startswith)
Ends with (-endswith)
Is null (-eq NULL)
Is not null (-ne NULL)

Most date and integer fields support:

Is equal to (-eq)
Is not equal to (-ne)
Is less than (-lt)
Is less than or equal to (-le)

Is greater than (-gt)
Is greater than or equal to (-ge)
Is null (-eq NULL)
Is not null (-ne NULL)

Most Boolean (true/false) fields support:

Is equal to (-eq)
Is not equal to (-ne)

Is null (-eq NULL)
Is not null (-ne NULL)

The results that match your search criteria will be displayed in the results grid below the search selection options. The results grid includes these fields:

Issued DN

The distinguished name of the certificate subject.

Import Date

The date the certificate was imported to Keyfactor Command. This field will auto populate on any new imports/enrollments of certificates. On an upgrade, this field will be populated in existing certificates from the certificate operation history.

Effective Date

The date the certificate was issued or became active.

Expiration Date

The date the certificate expires.

Issued CN

The common name of the certificate subject.

Issuer DN

The distinguished name of the certificate issuer.

Certificate Template

The short name of the template used to issue the certificate.

Principal Name

The identity that the certificate represents. The principal name field is populated during certificate synchronization by the user principal name (UPN) extracted from Active Directory if there is a principal name in the certificate subject alternative name The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. (SAN).

Requester

The user or entity that requested the certificate.

Locations

The server(s), if any, that the certificate is hosted on (e.g. for SSL certificates). If the certificate is found on multiple servers, this field will show the number of servers on which it was found and the location type (e.g. 4 SSL or 6 JKS). The specific server names can be found in the certificate details.

Key Type

The key type of the certificate.

Key Size

The key size of the certificate.

Certificate State

The certificate state options are:

Unknown (0)
Active (1)
Revoked (2)
Failed (4)
Pending (5)
Certificate Authority (6)
Parent Certificate Authority (7)

The search results can be sorted by clicking on a column header in the results grid for every column (except Certificate Locations, Key Type, and Certificate State). Click the column header again to reverse the sort order. The grid columns can be arranged in any order desired by click-holding and dragging the header of the column you wish to move. The column widths may be adjusted by click-holding and dragging the line separating two column headers.

You can check the Include Revoked and/or Include Expired boxes at the top of the results grid to toggle inclusion of revoked or expired certificates in the results. By default they are excluded.

The rest of the buttons at the top of the display grid are used to interact with the certificates displayed in the results grid. Some buttons are grayed out until you click on a grid row. Other certificate functions are available on the right-click menu. To open the right-click menu, highlight a row in the results grid and right-click. You can also double-click a certificate row in the results grid to open the Certificate Details (see Certificate Details).

To select a single row in the grid, click to highlight it and then select an operation from either the top of the grid or the right-click menu. Some of the certificate operations support action on multiple certificates at once. To select multiple rows, hold down the CTRL key and click each row on which you would like to perform an operation, or tick the check box next to the row. Then select an operation from the top of the grid. The right-click menu supports limited operations on the multiple certificates.

Advanced Searches

On any search page you can click Advanced to the right of the Search button to display the advanced search options. Click Simple to close the advanced search options again.

Multiple Criteria

Using the advanced search options, you can build a query based on multiple criteria using AND/OR logic. As with a simple search, you select a field and comparison operator in the drop-downs and then enter a comparison value, if applicable. Click Insert to add the search criteria to the query field below the selection fields. Use the selection fields to build multiple search criteria. Each time you click the insert button, an AND is added between the previous search criteria and the newly added one. You can change the AND to an OR if desired. You can use parentheses around portions of the query along with AND/OR to change the query meaning.

For example, for certificate searches:

(CN -contains "appsrvr" AND IssuedDate -ge "01/01/2022") OR (CN -contains "appsrvr" AND TemplateShortName -contains "web")

This query will return all the certificates issued on or after January 1, 2022 with the string appsrvr in the CN A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). and also all certificates issued at any time with the string appsrvr in the CN using a template referencing web. When you have entered all the desired search criteria, click Search to execute the query. If you wish to clear the query field and start over, click the Clear button.

Note: Multiple OR queries can be slow due to the nature of the query not being indexed and potentially requiring multiple queries of the database. To mitigate this, Keyfactor suggests you create a collection

The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports). for the subset of certificates, using the OR statement as needed, then perform a search starting with that collection and adding any additional conditions using advanced search from the search page. See Saving Search Criteria as a Collection.

In addition to the options available in the query builder, several special values can be used in selected searches by typing them in directly:

%TODAY%

Use the TODAY special value in place of a specific date in date queries. This option supports math operations, so you can use TODAY-10 or TODAY+30. The built-in Certificates Expiring in 7 Days collection uses this special value (see Certificate Collection Management).

Example: Create a certificate search of IssuedDate -ge "%TODAY-7%" and save it as a collection called Certificates Issued in the Last Week. Create another certificate search of ExpirationDate -lt "%TODAY+60%" and save it as a collection called Certificates Expiring in the Next 60 Days. This allows you to have saved collections containing a comparison date without having to update the date in the collection.

%ME%

Use the ME special value in place of a specific domain\user name in queries that match a domain\user name. The built-in My Certificates collection uses this special value (see Certificate Collection Management).

Example: Create a certificate search of NetBIOSRequester -contains "%ME%" and save it as a collection. Multiple users can now use this same collection to search for all the certificates on which they were the requester in the current domain.

Note: Certificate collections saved using the %ME% value are not supported for use in reports or on the dashboard.

%ME-AN%

Use the ME-AN special value in place of a specific user name excluding the domain. This is beneficial in environments with multiple domains where there is a desire to query for a user's certificates even if they were requested across multiple domains.

Example: Create a certificate search of NetBIOSRequester -contains "%ME-AN%" and save it as a collection. Multiple users can now use this same collection to search for all the certificates on which they were the requester, regardless of domain.

Note: Certificate collections saved using the %ME-AN% value are not supported for use in reports or on the dashboard.

%ROLES%

Use the ROLES special value in place of a specific security role in Owner Role Name queries to return all the certificates that are either marked as owned by a role of which the querying user is a member or not marked as owned by a role of which the querying user is a member. This option can be used only with the -in and -notin operators.

Example: Create a certificate search of OwnerRoleName -in "%ROLES%" and save it as a collection called Certificates Owned by My Roles. Multiple users can now use this same collection to view all the certificates in their owner group and take actions on them as applicable. Each user potentially sees a subset of all the certificates in the collection. Let’s say you have security roles Alpha, Beta, and Gamma and users assigned to security role Alpha should only see certificates of a certain type, users assigned to security role Beta should only see certificates of a different type, and users assigned to security role Gamma should only see certificates of a third type. You could create three different certificate collections, each containing only the certificates that the users in Alpha, Beta, and Gamma should see, respectively, and grant certificate collection permissions on these so that only the Alpha users had access to the alpha collection and so forth. But, with the %ROLES% token, you can create a single collection that contains the certificates that all three groups of users should be able to see plus the OwnerRoleName -in "%ROLES%" search string, assign certificate ownership on the certificates appropriately so that the Alpha users own the certificates they should see and so forth, and when an Alpha user opens the collection, he sees only the certificates he should see while when a Beta user opens the collection, he sees different certificates—the certificates he should see.

Note: Certificate collections saved using the %ROLES% value are not supported for use in reports or on the dashboard.

Note: If the user’s roles have changed, it may take a few minutes for the query to update to reflect the user’s new role membership.

Important: The special query options of %TODAY%, %ME%, %ME-AN%, and %ROLES% are only supported in uppercase. Lowercase equivalents (e.g. %me%) cannot be substituted.

To build a deep link with your search criteria, begin with the following URL (where KEYFACTOR_SERVER_FQDN is the FQDN of your Keyfactor Command administration server):

https://KEYFACTOR_SERVER_FQDN/keyfactorportal/CertificateCollection/Query?query=YOUR_URL_ENCODED_QUERY

Your Management Portal may have been configured to use HTTP rather than HTTPS.

Replace YOUR_URL_ENCODED_QUERY with your search criteria as built using the advanced search. The search criteria needs to be URL encoded, so, for example, spaces need to be replaced with %20 and quotation marks with %22. However, many modern browsers will automatically do this for you. A deep link using part of the example search shown above would look something like this without URL encoding:

https://keyfactor.keyexample.com/keyfactorportal/CertificateCollection/Query?query=CN -contains "appsrvr"

And with URL encoding, like this:

https://keyfactor.keyexample.com/keyfactorportal/CertificateCollection/Query?query=CN%20-contains%20%22appsrvr%22

Tip: Click the help icon (

) next to the Certificate Search Page page title to open the Keyfactor Software & Documentation Portal to this section. You will receive a prompt indicating:

You are being redirected to an external website. Would you like to proceed?

You can also find the help icon () at the top of the page next to the Log Out button. From here you can choose to open either the Keyfactor Software & Documentation Portal at the home page or the Keyfactor API Endpoint Utility.

Keyfactor provides two sets of documentation: the On-Premises Documentation Suite and the Managed Services Documentation Suite. Which documentation set is accessed is determined by the Application Settings: On-Prem Documentation setting (see Application Settings: Console Tab).

Version v24.4

On this page: